﻿using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace LearnCSharp
{
    /*
     * *************************************************************************************
     * *************************************************************************************
     *                                      COMMENTAIRES
     * *************************************************************************************
     * *************************************************************************************
    */

    /// <summary>
    ///  Description de la CommentaireSimple
    /// </summary>
    class CommentaireSimple
    {
        // 1- Commentaire simple

        /* 2- Commentaire sur un bloc
        public void fonction1()
        {
            int i = 0;
            i++;
        }
        */

        /*
         * 3- Commentaire
         * sur plusieurs lignes
         * 
         */

        // 4- Technique pour commenter un bloc de code avec déjà des commentaires /**/
#if false
        /* Commentaire sur un bloc
        public void fonction1()
        {
            int i = 0;
            i++;
        }
        */
#endif


        /// <summary>
        /// Variable pour faire apparaitre la classe dans la documentation générée (voir ci dessous)
        /// </summary>
        public static string monCommentaireSimple;

        /// <summary>
        /// Fonction utilisant la variable
        /// </summary>
        public void ChangeCommentaireSimple()
        {
            monCommentaireSimple = "my comment";
        }
    }

    /* 
     * Outils de génération de documentation du code source
     * - SandCastle (Microsoft, spécialisé .Net mais un peu vieux 2010)
     * - NDoc (vieux, dernière release en 2005)
     * - Doxygen (non spécif .Net)
     */

    /*
     * TUTO SandCastle : 
     * Outils à télécharger :
     *      - Sandcastle 2.7
     *      - SandCastle Help File Builder 1.9
    */

    /*
     * Récap des balises utilisables pour les commentaire :
     * - summary :  Généralité
     * - param :    Paramètres de la fonction
     * - returns :  Valeur de retour de la fonction 
     * - value :    Valeur d'une variable globale
     * - remarks :  Remarques
     * - exception : Type exception
     * - example :  Exemple d'utilisation
     * - 
     * 
     * - paramref : Indique que le mot dans le commentaire est un paramètre de la fonction
     * - c :        Indiquer que le mot est un mot faisant partie du code
     * - code :     Indique que le texte est du code
     * - see :      Lien vers un élément documenté grâce au nom de cet élément
     * - seealso :  Lien en bas de la page de documentation (lien externe)
     * 
     * - list :     Liste de type TABLE, BULLET, NUMBER
    */
    /// <summary>
    /// Description du domaine <see cref="TypeCSharp"/> incluant les classe CommentaireSimple et CommentaireDocumentation
    /// </summary>
    [System.Runtime.CompilerServices.CompilerGenerated]
    class NamespaceDoc
    {
    }

    /// <summary>
    /// Classe permettantde définir un commentaire en C# et interprétable par un générateur de documentation du code source
    /// </summary>
    public class CommentaireDocumentation
    {
        /// <summary>
        /// Variable définissant le commentaire
        /// </summary>
        public static string monCommentaire;

        /// <summary>
        /// Fonction permettant de changer <c>monCommentaire</c>
        /// </summary>
        /// 
        /// <exception cref="Exception">Exception levé si plantage</exception>
        /// 
        /// <example>Voila un exemple d'utilisation de la méthode 
        /// <code>this.ChangeComment("mon nouveau commentaire");</code>
        /// </example>
        /// 
        /// <seealso cref="System.Object">System.Text</seealso>
        /// 
        /// <param name="strComment">Paramètre définissant le nouveau comentaire </param>
        /// 
        /// <returns>Booléen indiquant si le changement de commentaire a été oppéré </returns>
        /// 
        /// <value>Retourne true si <c>monCommentaire</c> a bien été remplacé par celui défini par le paramètre en entrée <paramref name="strComment" /></value>
        /// 
        /// <remarks>
        ///     Fonction permettant de s'exercer sur les commantaire interprétable 
        ///     par un générateur de documentation grâce à l'attribut public <see cref="monCommentaire">Commentaire</see>
        ///     <list type="table">
        ///			<listheader>
        ///				<term>Titre 1</term>
        ///				<description>Description titre 1</description>
        ///				<description>Description titre 1 BIS</description>
        ///			</listheader>
        ///			<item>
        ///				<term>Terme 1.1</term>
        ///				<description> Description 1.1 en mode TABLE </description>
        ///				<description> Description BIS 1.1 en mode TABLE </description>
        ///			</item>
        ///			<item>
        ///				<term>Terme 1.2</term>
        ///				<description> Description 1.2 en mode TABLE </description>
        ///				<description> Description BIS 1.2 en mode TABLE </description>
        ///			</item>
        ///			<item>
        ///				<term>Terme 1.3</term>
        ///				<description> Description 1.3 en mode TABLE </description>
        ///				<description> Description BIS 1.3 en mode TABLE </description>
        ///			</item>
        ///		</list>
        ///		
        ///		<list type="bullet">
        ///			<item>
        ///				<term>Terme 2.1 </term>
        ///				<description> Description 2.1 en mode BULLET</description>
        ///			</item>
        ///			<item>
        ///				<term>Terme 2.2 </term>
        ///				<description> Description 2.2 en mode BULLET</description>
        ///			</item>
        ///			<item>
        ///				<term>Terme 2.3 </term>
        ///				<description> Description 2.3 en mode BULLET</description>
        ///			</item>
        ///		</list>
        ///		
        ///		<list type="number">
        ///			<item>
        ///				<term>Terme 3.1 </term>
        ///				<description> Description 3.1 en mode NUMEROTATION</description>
        ///		    </item>
        ///			<item>
        ///				<term>Terme 3.2 </term>
        ///				<description> Description 3.2 en mode NUMEROTATION</description>
        ///		    </item>
        ///			<item>
        ///				<term>Terme 3.3 </term>
        ///				<description> Description 3.3 en mode NUMEROTATION</description>
        ///			</item>
        ///		</list>
        ///  </remarks>
        public bool ChangeComment(string strComment)
        {
            try
            {
                if (monCommentaire == strComment)
                {
                    monCommentaire = strComment;
                    return true;
                }

            }
            catch (Exception e)
            {
                Console.WriteLine("{0} First exception caught.", e);
            }

            return false;
        }
    }
}
